package com.carbeauty.service;

import com.carbeauty.entity.Customer;
import com.carbeauty.common.enums.BusinessStatus;
import org.springframework.data.domain.Page;
import org.springframework.data.domain.Pageable;

import java.math.BigDecimal;
import java.util.List;
import java.util.Optional;

/**
 * 客户服务接口
 * 
 * 提供客户管理的业务逻辑:
 * - 客户基础CRUD操作
 * - 客户信息查询和搜索
 * - 会员等级管理
 * - 余额和积分管理
 * - 客户统计分析
 * 
 * @author CarBeauty Team
 */
public interface CustomerService {
    
    // ==================== 基础CRUD操作 ====================
    
    /**
     * 保存客户信息
     * 
     * @param customer 客户信息
     * @return 保存后的客户信息
     */
    Customer save(Customer customer);
    
    /**
     * 根据ID查找客户
     * 
     * @param id 客户ID
     * @return 客户信息
     */
    Optional<Customer> findById(Long id);
    
    /**
     * 根据ID获取客户（如果不存在抛出异常）
     * 
     * @param id 客户ID
     * @return 客户信息
     * @throws RuntimeException 客户不存在时抛出异常
     */
    Customer getById(Long id);
    
    /**
     * 删除客户（逻辑删除）
     * 
     * @param id 客户ID
     */
    void deleteById(Long id);
    
    /**
     * 批量删除客户
     * 
     * @param ids 客户ID列表
     */
    void deleteByIds(List<Long> ids);
    
    // ==================== 查询操作 ====================
    
    /**
     * 查找所有活跃客户
     * 
     * @return 活跃客户列表
     */
    List<Customer> findAllActive();
    
    /**
     * 分页查询活跃客户
     * 
     * @param pageable 分页参数
     * @return 客户分页数据
     */
    Page<Customer> findAllActive(Pageable pageable);
    
    /**
     * 根据手机号查找客户
     * 
     * @param phone 手机号
     * @return 客户信息
     */
    Optional<Customer> findByPhone(String phone);
    
    /**
     * 根据会员卡号查找客户
     * 
     * @param cardNo 会员卡号
     * @return 客户信息
     */
    Optional<Customer> findByCardNo(String cardNo);
    
    /**
     * 多条件搜索客户
     * 
     * @param name 客户姓名（模糊匹配）
     * @param phone 手机号（模糊匹配）
     * @param carNumber 车牌号（模糊匹配）
     * @param memberLevel 会员等级
     * @return 符合条件的客户列表
     */
    List<Customer> searchCustomers(String name, String phone, String carNumber, String memberLevel);
    
    /**
     * 分页搜索客户
     * 
     * @param name 客户姓名
     * @param phone 手机号
     * @param carNumber 车牌号
     * @param memberLevel 会员等级
     * @param pageable 分页参数
     * @return 客户分页数据
     */
    Page<Customer> searchCustomers(String name, String phone, String carNumber, String memberLevel, Pageable pageable);
    
    // ==================== 会员管理 ====================
    
    /**
     * 根据会员等级查找客户
     * 
     * @param memberLevel 会员等级
     * @return 客户列表
     */
    List<Customer> findByMemberLevel(String memberLevel);
    
    /**
     * 升级客户会员等级
     * 
     * @param customerId 客户ID
     * @param newLevel 新会员等级
     * @return 更新后的客户信息
     */
    Customer upgradeMemberLevel(Long customerId, String newLevel);
    
    /**
     * 获取会员等级统计
     * 
     * @return 各会员等级的客户数量统计
     */
    List<Object[]> getMemberLevelStatistics();
    
    /**
     * 查找VIP客户
     * 
     * @return VIP客户列表
     */
    List<Customer> findVipCustomers();
    
    // ==================== 余额管理 ====================
    
    /**
     * 客户充值
     * 
     * @param customerId 客户ID
     * @param amount 充值金额
     * @param bonusAmount 赠送金额
     * @param operatorId 操作员ID
     * @param paymentMethod 支付方式
     * @return 充值后的客户信息
     */
    Customer recharge(Long customerId, BigDecimal amount, BigDecimal bonusAmount, 
                     Long operatorId, String paymentMethod);
    
    /**
     * 客户消费扣款
     * 
     * @param customerId 客户ID
     * @param amount 消费金额
     * @return 扣款后的客户信息
     */
    Customer consume(Long customerId, BigDecimal amount);
    
    /**
     * 查找余额不足的客户
     * 
     * @param threshold 余额阈值
     * @return 余额不足的客户列表
     */
    List<Customer> findLowBalanceCustomers(BigDecimal threshold);
    
    /**
     * 获取客户余额排行榜
     * 
     * @param limit 排行榜数量
     * @return 余额排行榜
     */
    List<Customer> getBalanceRanking(int limit);
    
    // ==================== 积分管理 ====================
    
    /**
     * 增加客户积分
     * 
     * @param customerId 客户ID
     * @param points 积分数量
     * @return 更新后的客户信息
     */
    Customer addPoints(Long customerId, Integer points);
    
    /**
     * 扣减客户积分
     * 
     * @param customerId 客户ID
     * @param points 积分数量
     * @return 更新后的客户信息
     */
    Customer deductPoints(Long customerId, Integer points);
    
    /**
     * 获取客户积分排行榜
     * 
     * @param limit 排行榜数量
     * @return 积分排行榜
     */
    List<Customer> getPointsRanking(int limit);
    
    // ==================== 消费统计 ====================
    
    /**
     * 更新客户消费信息
     * 
     * @param customerId 客户ID
     * @param consumptionAmount 消费金额
     * @return 更新后的客户信息
     */
    Customer updateConsumption(Long customerId, BigDecimal consumptionAmount);
    
    /**
     * 获取消费排行榜
     * 
     * @param limit 排行榜数量
     * @return 消费排行榜
     */
    List<Customer> getConsumptionRanking(int limit);
    
    /**
     * 查找高价值客户
     * 
     * @param minConsumption 最小消费金额
     * @return 高价值客户列表
     */
    List<Customer> findHighValueCustomers(BigDecimal minConsumption);
    
    // ==================== 客户活跃度分析 ====================
    
    /**
     * 查找活跃客户（最近30天有消费）
     * 
     * @return 活跃客户列表
     */
    List<Customer> findActiveCustomers();
    
    /**
     * 查找沉睡客户（超过指定天数未消费）
     * 
     * @param days 天数
     * @return 沉睡客户列表
     */
    List<Customer> findInactiveCustomers(int days);
    
    /**
     * 获取客户活跃度统计
     * 
     * @return 客户活跃度统计信息
     */
    Object getCustomerActivityStatistics();
    
    // ==================== 数据统计 ====================
    
    /**
     * 获取客户总数统计
     * 
     * @return 客户总数
     */
    long getTotalCustomerCount();
    
    /**
     * 获取今日新增客户数量
     * 
     * @return 今日新增客户数量
     */
    long getTodayNewCustomerCount();
    
    /**
     * 获取本月新增客户数量
     * 
     * @return 本月新增客户数量
     */
    long getThisMonthNewCustomerCount();
    
    /**
     * 获取客户总余额
     * 
     * @return 客户总余额
     */
    BigDecimal getTotalBalance();
    
    /**
     * 获取客户总积分
     * 
     * @return 客户总积分
     */
    Long getTotalPoints();
    
    /**
     * 获取客户总消费金额
     * 
     * @return 客户总消费金额
     */
    BigDecimal getTotalConsumption();
    
    /**
     * 获取平均消费金额
     * 
     * @return 平均消费金额
     */
    BigDecimal getAverageConsumption();
    
    /**
     * 获取客户综合统计信息
     * 
     * @return 客户统计信息
     */
    Object getCustomerStatistics();
    
    // ==================== 数据验证 ====================
    
    /**
     * 验证手机号是否已存在
     * 
     * @param phone 手机号
     * @param excludeId 排除的客户ID（用于更新时验证）
     * @return 是否存在
     */
    boolean isPhoneExists(String phone, Long excludeId);
    
    /**
     * 验证会员卡号是否已存在
     * 
     * @param cardNo 会员卡号
     * @param excludeId 排除的客户ID
     * @return 是否存在
     */
    boolean isCardNoExists(String cardNo, Long excludeId);
    
    /**
     * 生成唯一的会员卡号
     * 
     * @return 会员卡号
     */
    String generateUniqueCardNo();
}
